package com.kexio.user.service;

import java.util.List;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.kexio.user.dto.TenantDTO;
import com.kexio.user.entity.Tenant;

/**
 * 租户管理服务接口
 * 
 * 提供完整的租户管理功能，包括：
 * - CRUD操作：创建、查询、更新、删除租户
 * - 状态管理：启用/禁用租户状态
 * - 分页查询：支持条件筛选的分页查询
 * - 统计功能：用户数量、活跃度等统计
 * - 验证功能：租户存在性、格式验证等
 * 
 * @author kexio
 * @since 1.0.0
 */
public interface TenantService {
    
    /**
     * 检查租户是否存在
     * 
     * @param tenantId 租户ID
     * @return 是否存在
     */
    boolean existsByTenantId(String tenantId);

    /**
     * 根据租户ID查询租户状态
     *
     * @param tenantId 租户ID
     * @return 租户状态：0-禁用, 1-正常, 2-试用, 3-过期, 4-待审核
     */
    Integer getTenantStatus(String tenantId);

    /**
     * 根据租户ID查询租户信息
     *
     * @param tenantId 租户ID
     * @return 租户信息
     */
    Tenant getTenantByTenantId(String tenantId);

    /**
     * 查询租户下的用户数量
     *
     * @param tenantId 租户ID
     * @return 用户数量
     */
    int getUserCountByTenantId(String tenantId);

    /**
     * 检查租户状态是否有效（可以正常使用）
     *
     * @param tenantId 租户ID
     * @return 是否有效
     */
    boolean isValidTenant(String tenantId);

    /**
     * 验证租户ID格式是否合法
     *
     * @param tenantId 租户ID
     * @return 是否合法
     */
    boolean isValidTenantIdFormat(String tenantId);

    // ==================== CRUD 方法 ====================

    /**
     * 创建新租户
     *
     * @param request 租户创建请求
     * @return 创建的租户实体
     * @throws IllegalArgumentException 当租户ID已存在或参数无效时
     */
    Tenant createTenant(TenantDTO request);

    /**
     * 根据ID查询租户详情
     *
     * @param id 租户主键ID
     * @return 租户实体，不存在时返回null
     */
    Tenant getTenantById(String id);

    /**
     * 更新租户信息
     *
     * @param tenantId 租户业务ID
     * @param request 更新请求
     * @return 更新后的租户实体
     * @throws IllegalArgumentException 当租户不存在或参数无效时
     */
    Tenant updateTenant(String tenantId, TenantDTO request);

    /**
     * 删除租户（软删除）
     *
     * @param tenantId 租户业务ID
     * @return 是否删除成功
     * @throws IllegalStateException 当租户下还有用户时
     */
    boolean deleteTenant(String tenantId);

    /**
     * 更新租户状态
     *
     * @param tenantId 租户业务ID
     * @param status 新状态：0-禁用, 1-正常, 2-试用, 3-过期, 4-待审核
     * @return 是否更新成功
     */
    boolean updateTenantStatus(String tenantId, Integer status);

    // ==================== 分页查询方法 ====================

    /**
     * 分页查询租户列表
     *
     * @param current 页码（从1开始）
     * @param size 每页大小
     * @return 分页结果
     */
    Page<Tenant> getTenantPage(Long current, Long size);

    /**
     * 分页查询租户列表（支持条件筛选）
     *
     * @param current 页码（从1开始）
     * @param size 每页大小
     * @param tenantName 租户名称（模糊匹配）
     * @param status 租户状态
     * @param tenantType 租户类型
     * @return 分页结果
     */
    Page<Tenant> getTenantPage(Long current, Long size, String tenantName, Integer status, String tenantType);

    /**
     * 获取所有活跃租户列表（用于下拉选择）
     *
     * @return 活跃租户列表
     */
    List<Tenant> getActiveTenants();

    // ==================== 统计和验证方法 ====================

    /**
     * 检查租户名称是否已存在
     *
     * @param tenantName 租户名称
     * @param excludeTenantId 排除的租户ID（更新时使用）
     * @return 是否已存在
     */
    boolean existsByTenantName(String tenantName, String excludeTenantId);

    /**
     * 获取租户总数统计
     *
     * @return 租户总数
     */
    long getTotalTenantCount();

    /**
     * 获取活跃租户数统计
     *
     * @return 活跃租户数（状态为1的租户）
     */
    long getActiveTenantCount();

    /**
     * 获取即将过期的租户数量
     *
     * @param days 多少天内过期
     * @return 即将过期的租户数量
     */
    long getExpiringTenantCount(int days);

    /**
     * 检查租户是否可以添加更多用户
     *
     * @param tenantId 租户ID
     * @return 是否可以添加用户
     */
    boolean canAddMoreUsers(String tenantId);

    /**
     * 获取租户的剩余用户配额
     *
     * @param tenantId 租户ID
     * @return 剩余用户数，-1表示无限制
     */
    int getRemainingUserQuota(String tenantId);
}
